CD Ware Multimedia 1995 May

home *** CD-ROM | disk | FTP | other *** search

/ CD Ware Multimedia 1995 May / cd Ware (Juegos) Epimundo.iso / DOS / C / GPORT.ZIP / GPORT.DOC < prev next >

Wrap

Text File | 1993-04-09 | 26.4 KB | 1,164 lines

Gport C Language Game Port Library Version 1.01 1 September 91 Copyright (c) 1991 Bri Productions 1 Table of Contents Introduction General Description.....................3 Disclaimer..............................3 Registration............................3 Contacting the Author...................3 A typedef...............................3 General Functions Description.............................4 GamOpen.................................5 GamClose................................6 GamAxis.................................6 GamAxes.................................7 GamButton...............................8 Calibration Functions Description............................10 GamRawAxis.............................11 GamCalAxis.............................12 GamCenter..............................13 Appendix A - Things to Look Out For............15 Appendix B - Joystick Calibration/Centering....16 Appendix C - Registration Form.................18 2 General Description. Gport is a C language, high speed, high resolution game port library for IBM and compatible computers. Gport is compatible with most if not all DOS based C compilers. Some of Gport's features are: ∙ Timer driven button monitor. ∙ Optional joystick calibration. ∙ Choice of REAL or MEAN centering modes. ∙ Yields higher resolution on faster computers. ∙ Constant axis scaling to approximately ±1000. ∙ Written in assembly language for optimum speed and efficiency. DISCLAIMER. Gport is provided AS IS. Bri Productions specifically disclaims any and all warranties, expressed or implied, including fitness for a particular purpose. Use this product at your own risk. Registration. Gport is a user supported software product. Distribution of this product, unaltered and without charge, is encouraged. If you find this product useful, you are encouraged to register your copy. This allows Bri Productions to continue to provide and support low cost, high quality shareware. The registration fee is $25.00 US dollars and includes libraries for small, medium, compact and large memory models and complete source code. A registration form is provided in Appendix C. Contacting the author. Bri Productions may be contacted by any of the following means: U.S. mail - Bri Productions P.O.Box 7121 Fremont, CA 94537-7121 Phone - (510) 794-0616 CompuServe - 76635,2246 CompuServe is a trademark of CompuServe Inc. A typedef. You will see the data type 'byte' throughout the Gport library. This is a typedef defined in gport.h. Byte is an unsigned character used for byte size values. 3 General functions There are two functions that are required before other game port functions can be called. They are GamOpen() and GamClose(). GamOpen() initializes the game port and installs an interrupt handler for monitoring the buttons. GamClose() releases the interrupt handler. Failing to call GamClose() prior to the program's termination will most certainly cause an operating system crash. GamAxis() and GamAxes() fetches the position(s) of one or more joystick axes. A full up or right joystick returns a value of approximately +1000 and full down or left returns a value of approximately -1000. GamButton() fetches the status of the game port's buttons. Information on a button pressed since the last call to GamButton() as well as a presently pressed is available. 4 ---------------------------------------------------------------- GamOpen ---------------------------------------------------------------- Function Initializes the game port and installs the interrupt handler. Syntax #include "gport.h" int GamOpen(void); Remarks GamOpen initializes the game port. If an axis is found to be valid, it's corresponding bit is set in the returned status word. After a call to GamOpen, a subsequent call to GamClose is required. Failure to do so will most definitely cause the operating system to crash. Return Value GamOpen returns a valid axis status word. The bits/values are defined as follows: JAX_VAL (0x1) - Joystick A, x axis valid JAY_VAL (0x2) - Joystick A, y axis valid JA_VAL (0x3) - Joystick A, both axes valid JBX_VAL (0x4) - Joystick B, x axis valid JBY_VAL (0x8) - Joystick B, y axis valid JB_VAL (0xC) - Joystick B, both axes valid See also GamClose Example Attempt to open the game port and check Joystick A. { int valid_axes; valid_axes = GamOpen(); if((valid_axis & JA_VAL) == JA_VAL) { ...Joystick A OK } } 5 ---------------------------------------------------------------- GamClose ---------------------------------------------------------------- Function Releases the interrupt handler. Syntax #include "gport.h" void GamClose(void); Remarks After a call to GamOpen, a subsequent call to GamClose is required. Failure to do so will most definitely cause the operating system to crash. See also GamOpen Example Close the game port prior to terminating. { ...closing code GamClose(); exit(0) } ---------------------------------------------------------------- GamAxis ---------------------------------------------------------------- Function Gets the coordinate of a joystick axis. Syntax #include "gport.h" signed GamAxis(byte axis); 6 Parameters axis - Constant that defines which axis to get the coordinate of. Possibilities are: JAX (0) - Joystick A, X axis JAY (1) - Joystick A, Y axis JBX (2) - Joystick B, X axis JBY (3) - Joystick B, Y axis Remarks GamAxis fetches the coordinate of a single joystick axis. The coordinate is returned as a signed integer. Return value GamCoord returns the coordinate of the specified axis. The values will range from -1000 to +1000. See also GamAxes GamButton Example Update the current positions of the X & Y axes for joystick A. { YourXaxisFunction( GamAxis(JAX) ); YourYaxisFunction( GamAxis(JAY) ); } ---------------------------------------------------------------- GamAxes ---------------------------------------------------------------- Function Gets the both axes coordinates of a joystick. Syntax #include "gport.h" void GamAxes(byte stick, signed *x, signed *y); 7 Parameters stick - Constant that defines which joystick to get the coordinates of. Possibilities are: JA (0) - Joystick A JB (1) - Joystick B x - pointer to the signed integer where the x axis coordinate will be stored. y - pointer to the signed integer where the y axis coordinate will be stored. Remarks GamAxes fetches the coordinates of both axes for the specified joystick. The coordinates are stored at the pointers passed to GamAxes. The values will range from -1000 to +1000. See also GamAxis GamButton Example Update the current positions of the X & Y axes for joystick A. { signed x,y; GamAxes(JA, &x, &y); YourXaxisFunction( x ); YourYaxisFunction( y ); } ---------------------------------------------------------------- GamButton ---------------------------------------------------------------- Function Gets the status of the joystick buttons. 8 Syntax #include "gport.h" byte GamButton(void); Remarks GamButton returns the current status of the joystick buttons as well as any button status since the last call to GamButton. Return value GamButton returns the status of the joystick buttons. If the button is currently pressed, it's current bit will be set. If a button has been pressed since the last call to GamButton, it's pending bit is set. The bit constants are as follows: BA1_CURR (0x01) - Joystick A, button 1 current. BA2_CURR (0x02) - Joystick A, button 2 current. BB1_CURR (0x04) - Joystick B, button 1 current. BB2_CURR (0x08) - Joystick B, button 2 current. BA1_PEND (0x10) - Joystick A, button 1 pending. BA2_PEND (0x20) - Joystick A, button 2 pending. BB1_PEND (0x40) - Joystick B, button 1 pending. BB2_PEND (0x80) - Joystick B, button 2 pending. See also GamAxis GamAxes Example Check if the player has fired (button 1). If so call the fire update function. #define FIRE (BA1_PEND) | (BA1_CURR) { if(GamButton() & FIRE) { YourFireFunction(); ...more code } } 9 Calibration Functions The performance of the joystick can be significantly improved by calibrating it, especially if the joystick is misaligned. This is achieved by collecting the raw value of the position of the joystick extremes; full up, down, left, and right; and recalculating scaling math. GamRawAxis() fetches the raw value of the position of the joystick, which is passed to the function GamCalAxis(). GamCalAxis() then recalculates the scaling math. The calibration is done in two steps in order to leave open the option of saving the raw values to disk for future reference. This saves the step of having to recalibrate every time a program is run. GamCenter() sets the centering mode. There are two ways to determine where the center of a joystick is. The REAL center is defined as where the joystick comes to rest. The MEAN center is defined as the mean between the joystick extremes. For a more detailed description on calibration, see Appendix B. 10 ---------------------------------------------------------------- GamRawAxis ---------------------------------------------------------------- Function Gets the raw value of a joystick axis. Syntax #include "gport.h" unsigned GamRawAxis(byte axis); Parameters axis - Constant that defines which axis to get the coordinate of. Possibilities are: JAX (0) - Joystick A, X axis JAY (1) - Joystick A, Y axis JBX (2) - Joystick B, X axis JBY (3) - Joystick B, Y axis Remarks GamRawAxis returns the raw value of a joystick position to be used for calibrating the joystick . Smaller values are to the left and up while larger values are to the right and down. The actual value will vary from machine to machine. Return value GamRawAxis returns the raw value for the position of the selected joystick axis. See also GamCal GamCenter Example Calibrate the X axis on joystick A. { int raw_ax_right; int raw_ax_left; puts("Hold joystick full right and press any key"); getch(); 11 raw_ax_right = GamRawAxis(JAX); GamCalAxis(JAX, raw_ax_left); puts("Hold joystick full left and press any key"); getch(); raw_ax_left = GamRawAxis(JAX); GamCalAxis(JAX, raw_ax_right); } ---------------------------------------------------------------- GamCalAxis ---------------------------------------------------------------- Function Calibrates a joystick axis extreme from a raw value. Syntax #include "gport.h" void GamCalAxis(byte axis, unsigned raw_value); Parameters axis - Constant that defines which axis to get the coordinate of. Possibilities are: JAX (0) - Joystick A, X axis JAY (1) - Joystick A, Y axis JBX (2) - Joystick B, X axis JBY (3) - Joystick B, Y axis raw_value - Raw value returned from a call to GamRaw on which to calibrate. Remarks GamCalAxis calibrates a joystick extreme from a raw value from a previous call to GamRawAxis. Notice that it is not necessary to specify the extreme (left/right or up/down) in question. See also GamRawAxis GamCenter 12 Example Calibrate the X axis on joystick A. { puts("Hold joystick full right and press any key"); getch(); GamCalAxis(JAX, GamRawAxis(JAX)); puts("Hold joystick full left and press any key"); getch(); GamCalAxis(JAX, GamRawAxis(JAX)); } ---------------------------------------------------------------- GamCenter ---------------------------------------------------------------- Function Sets the centering mode. Syntax #include "gport.h" void GamCenter(byte mode); Parameters mode - Constant defining the centering mode to be used. Possibilities are: * REAL (0) - real centering mode. MEAN (1) - mean value centering. * default Remarks GamCenter sets the centering mode to be used. In real mode, the center of an axis will be where the joystick is at rest. In mean mode, the center is calculated as the mean between the two previously calibrated extremes. For a more detailed description of the centering modes see Appendix B. See also GamRawAxis GamCalAxis 13 Example Set the centering to mean mode. { GamCenter(MEAN); } 14 Appendix A Things to look out for. ∙ Gport installs a timer interrupt at interrupt 0x1C (user timer link). Gport does not take over this interrupt but chains into it. ∙ Some faster machines will exhibit a "fold back" on the down and right strokes of the joystick. Special AT game ports are available which usually resolve this problem. 15 Appendix B Calibration When the function GamOpen() is called, some assumptions are made about the raw values of the positions of the joystick extremes; left, right, up and down. The assumptions are based on the raw value of the joystick axes at the time of the call to GamOpen() (at rest at the center). In most cases the joystick will perform reasonably well providing the alignment of the joystick is at least fair. The performance of the joystick can be greatly improved if it is calibrated. Even a poorly aligned joystick can be made to appear to perform quite well. In order to accomplish this the assumptions about the joystick extremes must be replaced by their actual raw values. This requires the cooperation of the user as well as the functions GamRawAxis() and GamCalAxis(). Typically the user will be prompted to hold the joystick to each of the four extremes and hit a key on the keyboard. For each extreme, the raw value of the joystick position is read by a call to GamRawAxis() and the returned value is passes to GamCalAxis(). GamCalAxis will then make some recalculations and replace the previous assumptions (or calibration). Notice that the calibration is done in two steps. First the raw value is fetched and then it is passed. This allows the program to store the raw values for future reference. Next time the program is run, the values can be retrieved and passes directly to GamCalAxis(). This saves the step of having to interface with the user and calling GamRawAxis() every time the program runs. Centering There are two ways to interpret where the center of the joystick is . One way is to define the center as being where the joystick comes to rest. Gport port refers to this as REAL mode. The second way is to define the center as being equidistant, or at the mean, from all of the joystick extremes. Gport refers to this centering mode as MEAN mode. REAL mode has the obvious advantage that the joystick will always return approximately to the center. This will preclude any drifting. The disadvantage of REAL mode is that there is no evidence of how well the joystick is actually aligned. The advantage and disadvantage of MEAN mode is the complement of those of REAL mode. Drift will occur if the joystick is not aligned well. But since there will be the evidence of the joystick's misalignment, MEAN mode could be used to actually align a joystick. 16 Recall that MEAN mode refers to the joystick extremes. Also recall that the joystick extremes are assumed until the joystick is calibrated. For this reason there is little difference between the two centering modes until the joystick is calibrated. Calculating the mean center using the assumed extremes will result in the same center since the reverse process is used to calculate the assumed extremes. 17 Appendix C Gport Registration Form Name: ______________________________________________________ Company: ___________________________________________________ Address: ___________________________________________________ City: ____________________________ State: _________________ Zip code: _________________ Phone # : _____________________ CompuServe # : _____________________________________________ How did you acquire Gport ? _________________________________ ____________________________________________________________ What functions do you find most useful ?____________________ ____________________________________________________________ What functions do you find least useful ?___________________ ____________________________________________________________ What functions, not in Gport, would you like to see ?_______ ____________________________________________________________ What other types of libraries would you find useful ?_______ __ Serial Communications __ Expanded Memory __ IEEE/GPIB Others: ____________________________________________________ registration $ 25.00 California residents add sales tax ( 8.25% ) $________ shipping inside continental U.S. ( $ 2.00 ) shipping outside continental U.S. ( $ 5.00 ) $________ Total: $________ All Payments Must be in U.S. Dollars Make check or money order payable to: Bri Productions P.O. Box 7121 Fremont, CA 94537-7121 18 ----------------end-of-author's-documentation--------------- Software Library Information: This disk copy provided as a service of Public (software) Library We are not the authors of this program, nor are we associated with the author in any way other than as a distributor of the program in accordance with the author's terms of distribution. Please direct shareware payments and specific questions about this program to the author of the program, whose name appears elsewhere in this documentation. If you have trouble getting in touch with the author, we will do whatever we can to help you with your questions. All programs have been tested and do run. To report problems, please use the form that is in the file PROBLEM.DOC on many of our disks or in other written for- mat with screen printouts, if possible. PsL cannot debug pro- programs over the telephone, though we can answer questions. Disks in the PsL are updated monthly, so if you did not get this disk directly from the PsL, you should be aware that the files in this set may no longer be the current versions. Also, if you got this disk from another vendor and are having prob- lems, be aware that some files may have become corrupted or lost by that vendor. Get a current, working disk from PsL. For a copy of the latest monthly software library newsletter and a list of the 4,000+ disks in the library, call or write Public (software) Library P.O.Box 35705 - F Houston, TX 77235-5705 1-800-2424-PSL MC/Visa/AmEx/Discover Outside of U.S. or in Texas or for general information, Call 1-713-524-6394